CM-2 and CM-200 
Installation Instructions for 
Prism Version 1.2 


This is the CM-2/CM-200 installation guide for Prism Version 1.2. Read it com¬ 
pletely before attempting the installation. 


1.1 Planning the Installation 

General 

Perform the installation as superuser. 

You can run the installation from any directory to which you have write access 
as superuser. 

When answering any question during the installation, you can accept the default 
(which is indicated in square brackets) by simply pressing the Return key in 
response to the question. In addition, you can escape to a subshell at any time by 
entering ! (exclamation) in response to a question. 

In addition to installing a number of files, the Prism installation script needs to 
ensure that the file XKeysymDB exists on the user’s system and that it contains 
the correct OSF bindings required for Prism to work properly. Because of this, 
the installation procedure must be able to write into the X library directory. If for 
some reason the X library directory cannot be made writable, you can manually 
fix the XKeysymDB file by appending the contents of the XKeysymDB file that is 
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shipped in the Prism support directory to the currently installed version of the 
file. 

If there appears to be a serious problem with the installation, we recommend 
reinstalling from the tape and starting over. 


Choosing a Tape Drive 

The installation may be performed from either a local or a remote tape drive. You 
should first decide on which type you will use. In general, a local tape drive is 
preferable. 

Next, find the name of the non-rewinding tape device that you will be using for 
the installation. On a Sim, the reel tape is often /dev/nrmt8, and the cartridge 
tape is often /dev/nrsts. If you are not sure of the device name for your tape 
drive, check with your system administrator. 

Last, if you have decided to use a remote tape drive, make sure that you have root 
access to the remote system by executing the following command on the system 
where Prism is to be installed: 

# rsh remoteJiostjiame date 

If you receive a “Permission denied” message, you need to add the name of your 
machine to the /. xhosts file on the remote machine. 


1.2 Installation Components 

The base installation uses about 10.8 Mbytes of disk space. If you have a tape 
that includes the Prism source code, this requires another 5 Mbytes of disk space. 
Finally, the man pages you add separately to the on-line documentation database 
will require up to 3 Mbytes of disk space; see Section 1.6. 

Each component is described below. 
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Table 1. Prism components. 


Component 

Size 

Prism driver 

3 Kb 

Prism support directory 

10.7 Mb 

Prism runtime libraries 

150 Kb 

Prism manual page 

3 Kb 

Prism sample program 

1 Kb 

Prism source code (optional) 

5 Mb 


Prism Driver 

We suggest that this component be placed in /usr/local/bin. 


Prism Support Directory 

This component contains the internal files required for Prism to work correctly. 
We recommend that it be placed in /usr/local/lib. NOTE: The app-defaults 
file for Prism is in the app-defaults subdirectory of the support directory. 

The size of the support directory depends on the number of manual pages you 
add to the on-line documentation database. See Section 1.6. 

The ps subdirectory of the support directory contains compressed Postscript 
versions of the Prism User’s Guide and Prism Reference Manual. We recom¬ 
mend that you move these files after installation from /usr/lib to 
/usx/cm/doc/prism. 


Prism Runtime Libraries 

We suggest that this component be placed in /usr/local/lib. 
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Prism Manual Page 

We suggest that the man page be placed in the repository for CMost user manual 
pages, /usr /man/1 ocal /CMOST/manl. 


Prism Sample Program 

Prism provides a sample program that users can work with in the on-line tutorial. 
We recommend that you place the examples directory in the directory /usr/cm/ 
examples/. This will create the directory /usr/cm/examples/prism. 


Prism Source Code 

Some sites receive Prism’s source code on their release tape. There is no default 
location for this source code. 


1.3 Reading the Tape 

As mentioned earlier, you can install Prism from either a local or remote tape 
drive. In either case, the first step is to read the installation script off the tape. 

To do this, first become superuser and change to the directory from which you 
will do the installation. If you are doing the installation from a remote tape drive, 
skip to the section “Reading a Remote Tape.” If you are using a local tape drive, 
continue to the next section. 


Reading a Local Tape 

To unload the installation procedure from a local tape drive, issue the following 
commands: 


# mt -f tapejievice rew 

# mt -f tapejievice fsf 

# tar xf tapejievice 
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where tape_device is the name of the non-rewinding tape drive that you are using 
for the installation. 


For example: 

# mt -f /dev/nrmtoh rew 

# mt -f /dev/nrmtoh fsf 

# tar xf /dev/nrmtOh 


You can now skip the section “Reading a Remote Tape,” below, and continue 
with the Section 1.4. 


Reading a Remote Tape 

To unload the installation procedure from a remote tape drive, issue the follow¬ 
ing commands: 

# rsh remoteJiostjiame mt -£ tapejdevice rew 

# rsh remote Jiostjiame mt -£ tapejdevice fsf 

# rsh remote Jiostjiame dd L£’=tape_device ibs=hs | tar xpBf - 

where: 


remote Jiostjiame 

is the name of the machine with the tape drive. 

tapejdevice is the device name of the remote non-rewinding tape 
drive. 

bs is the blocksize to use when reading the tape. If you are 

reading from a reel (9-track) tape, then bs is 20b. If you 
are using a Sun cartridge, then bs is 126b. 

For example: 

# rsh cmns mt -£ /dev/nrmtoh rew 

# rsh cmns mt -£ /dev/nrmtOh fsf 

# rsh cmns dd If ■=/dev/nrmtoh ibs=20b | tar xpBf - 
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1.4 Installing Prism Version 1.2 

Issuing the Command 

To install Prism, issue this command: 

# ./Install 1.2 


Answering the Questions 

First you will be asked a set of questions about the tape drive that you are using. 
Having gotten this far in the installation process, you should find the answers 
straightforward. The questions are listed below. 

Is this a remote installation? [n] 

Enter the name of the tapeserver host [no default] 

What is the name of your non-rewinding tape drive device? [/dev/nrst8] 

Is the distribution on a cartridge tape? [y] 

Next, you can elect to see the name of each file as it is extracted from the tape. 
If you want a detailed list of the files being installed, answer yes to this question: 

Should the files be extracted from the tape verbosely? [n] 

You will then be asked to make sure that the tape is mounted and ready. Don’t 
be alarmed that the procedure is asking for Tape 1; the Prism installation uses 
only one tape. 


Is tape 1 mounted and ready to go? [Type carriage return when ready] 

The next set of questions take care of installing each of the components of Prism. 
After each question is answered, the installation script will unload that compo¬ 
nent into the location you specify. 

Where do you want to put the Prism Driver [/usr/local/bin]? 

Where do you want to put the Prism Support Directory [/usr/local/lib]? 

Where do you want to put the Prism Runtime Libraries [/usr/local/lib]? 

Where do you want to put the Prism Manual Page [/usr/local/man/CMOST/manl] ? 

Where do you want to put the Prism Examples Directory [/usr/cm/examples]? 

If your tape includes the Prism source code, an additional question appears: 

Reading the optional Prism Source Code. 

Do you want the Prism Source Code? 

There is no default location for the source code. Specify any location for it. 
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Everything has now been read from the tape. The installation procedure then 
asks: 

Where is the X library directory on this machine [/usr/lib/Xll]? 

Where are the Paris libraries on this machine [/usr/local/lib]? 

Compiling CM2 attach verification utility... 

The next questions asked by the procedure are used to customize the installation 
to the environment at your site. The first three of these questions will ask for a 
pathname that is valid from a user’s point of view. The pathnames that you spec¬ 
ify in this section might be different from those that you specified when you 
unloaded the tape. This might be the case, for example, if you are installing 
Prism onto a server that will be exporting the Prism directories to client machines 
from which users will be running Prism. In this case, the pathname used to access 
a directory on the server may be different from the pathname used to access that 
same server directory from the client. 

Note that your responses to these questions do not make soft links. If you are 
going to use links, respond to this set of questions with the locations of the 
installed software (that is, what the soft links should point at), not the locations 
of the soft links that are going to be installed. 

The questions are shown below. 

Where would a user find the Prism Support Directory [/usr/local/lib]? 

Where would a user find the Prism Runtime Libraries [/usr/local/lib]? 

Where would a user find the Prism Driver [/usr/local/bin]? 

Where would a user find the Prism Manual Page [/usr/local/man/CMOST/manl]? 

Where would a user find the X library directory [/usr/lib/Xll]? 

Next, the installation script asks about soft links: 

Do you want to install soft links [no]? 

If you answer yes, the script asks: 

In what directory should the driver link be created [/usr/local/bin]? 

In what directory should the library links be created [/usr/local/lib]? 

In what directory should the man page link be created [/usr/local/man/CMOST/manl]? 

It then continues: 

The Prism 'email' command allows users to submit bug reports from within Prism. 
Enter a valid e-mail address to which these messages should be sent. If your site 
has a local Applications Engineer, the AE's e-mail address should be given, other¬ 
wise the e-mail should be directed to Customer Support at Thinking Machines 
(csg@think.com). 

Enter a valid e-mail address for Prism bug reports [no_default]?With each software 
release Thinking Machines will now be sending an ASCII 
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bug-update file that lists fixed bugs and outstanding bugs for Prism. We 
will also be sending monthly updates to this file. 

This release also includes an ASCII version of the Prism release notes 
for version 1.2 

The bug-update file for this release is called prism-1.2.bugupdate. 

The release notes file for this release is called prism-1.2.releasenotes. 

Where would you like to install these two files [/usr/cm/doc]? 

After you have answered these questions, the installation procedure will build a 
simple version of the on-line documentation database. See Section 1.6 for 
information on how to add manual pages to this database. 

The installation procedure then ranlibs the Prism runtime library. This completes 
the basic installation of Prism. 

NOTE: Don’t forget to move the compressed Postscript versions of the Prism 
manuals from the ps subdirectory of your support directory to /usr/cm/doc/ 
prism, and then uncompress them. 


1.5 Verifying the Installation 

We suggest that you verify the installation by starting Prism and making sure that 
the help system and the on-line documentation system work. To start Prism, issue 
these commands (substituting the name of your own workstation for worksta¬ 
tion ): 

% rehash 

% setenv DISPLAY workstation :0 
% prism 

The rehash may be necessary to update the shell’s hash tables to see the newly 
installed prism command. After Prism starts up, pull down the Help menu and 
click on any selection to make sure the help fries are available. Pull down the Doc 
menu and click on Online Doc. Submit a topic (for example, “attaching”) and 
make sure that the documentation is available. If there is a problem with on-line 
documentation, see below. 

It may be the case, however, that you will be able to obtain on-line documenta¬ 
tion but other users will not; this will happen if Prism is installed onto a server 
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that exports Prism to other machines, and the pathname to the support directory 
is different on the server and the client. See below for a workaround. 


If On-line Documentation Isn’t Working 

You may find that on-line documentation isn’t working. In the Xwais window 
that appears when you click on Online Doc, you may see the message: 

The following database is not available: ... 

And in the xterm from which you started Prism, you may see the message: 

can't open the word hash file ... 

This problem can occur if the Prism support directory was installed into a file 
system that is mounted on the installation system via the Sun automounter. 

The workaround is to log in to the machine that exports the file system on which 
the Prism support directory resides and manually build the on-line documenta¬ 
tion database by issuing these commands: 

# cd prism-support-directory/online 

# ./waisindex -r -d tmc-documentation -V /usr/local/lib cm2 common site 

(In the second command, /usr/local/lib is the default path for the Prism 
support directory from the user’s point of view. If you have specified a different 
path during installation, use it instead.) 


1.6 Adding Manual Pages to the 
On-line Documentation Database 

The Prism installation now includes a utility, build_database, that lets you 
update its on-line documentation database to include the latest versions of CM 
manual pages. We recommend that you run this utility immediately after instal¬ 
ling Prism, since Prism does not include man pages in the on-line documentation 
database it creates as part of the installation. You can then run this utility at any 
time subsequently to update the database. 

NOTE: This utility can take a long time to run to completion. 
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The utility asks you to enter the names of man page directories; it will include 
all the Thinking Machines’ man pages in these directories in its processing. (You 
can add and delete directories until you are satisfied with your list.) Note these 
rules in specifying directories: 

■ If you specify a directory, build_database includes all the subdirecto¬ 
ries that have uppercase letters in their names . (It does this because CM 
man page directories have uppercase names.) 

■ Otherwise, build_database interprets names and wildcards in the stan¬ 
dard manner. For example, if you specify /usr/local/man/*, it 
includes all subdirectories of /usr/local/man. 

Run the utility as superuser. Begin by changing to the utilities subdirectory of the 
Prism support directory: 

# cd /usr/local/lib/prism_dirl. 2/util 

(If the Prism support directory isn’t in /usr/local/lib, substitute the correct 
path.) Then issue this command: 

# . /build_database 
The utility responds: 

This utility strips Thinking Machines man pages and 
includes them in the Prism on-line documentation data¬ 
base . 

Please enter the names of one or more directories that 
contain man pages. For example, /usr/man or /usr/local/ 
man. 

Once you have correctly entered all desired directory 
names, this procedure will run to completion without any 
further questions. 

To add a new directory, enter its pathname followed by a 
RETURN. 

To delete an entry from the directory list, enter its 
number followed by a RETURN. 

To begin processing man pages, just enter a RETURN. 

Multiple directories or multiple numbers are also legal 
responses. In addition, shell wildcard characters can be 
used when specifying directories. 


Version L2 




Prism Installation Guide 11 


At this point, you might respond as follows: 

Enter a number, a directory, or a RETURN: /usr/local/man 
The utility would then list the directories you have chosen. For example: 

The current directory list: 

0. /usr/local/man/CMF 

1. /usr/local/man/CMFS 

2. /usr/local/man/CMOST 

3. /usr/local/man/CMSSL 

4. /usr/local/man/PARIS 

5. /usr/local/man/XHR5 

6. /usr/local/man/XHR5 . v2 

To add a new directory, enter its pathname followed by a 
RETURN. 

To delete an entry from the directory list, enter its 
number followed by a RETURN. 

To begin processing man pages, just enter a RETURN. 

Multiple directories or multiple numbers are also legal 
responses. In addition, shell wildcard characters can be 
used when specifying directories. 

Enter a number, a directory, or a RETURN: 

You probably don’t want bulldjiatabase to process the Xll directories, 
since this will just slow things down, so you would remove them from the list: 

Enter a number, a directory, or a RETURN: 5 6 

And the utility would show the revised list: 

The current directory list: 

0. /usr/local/man/CMF 

1. /usr/local/man/CMFS 

2. /usr/local/man/CMOST 

3. /usr/local/man/CMSSL 

4. /usr/local/man/PARIS 

To add a new directory, enter its pathname followed by a 
RETURN. 

To delete an entry from the directory list, enter its 
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number followed by a RETURN. 

To begin processing man pages, just enter a RETURN. 

Multiple directories or multiple numbers are also legal 
responses. In addition, shell wildcard characters can be 
used when specifying directories. 

Enter a number, a directory, or a RETURN: 

If you are satisfied with the directory list, press return. The utility responds: 

The following directories will be processed: 

/usr/local/man/CMF 
/usr/local/man/CMFS 
/usr/local/man/CMOST 
/usr/local/man/CMSSL 
/usr/local/man/PARIS 

filtered: acos.3 
filtered: AC0S.3 
filtered: AIMAG.3 
filtered: AINT.3 
filtered: ALL.3 ... 

The utility continues until it has filtered all the man pages and added them to the 
database. 
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